home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #5 & #6 / Amiga Plus CD - 1995 - No. 5 and 6.iso / pd / daten / ispell / source / amiga / doc / fields3.txt < prev    next >
Text File  |  1995-06-29  |  13KB  |  265 lines
  1.  
  2.  
  3.  
  4. FIELDS(3)                                               FIELDS(3)
  5.  
  6.  
  7. NNAAMMEE
  8.        fieldread, fieldmake, fieldwrite, fieldfree - field access
  9.        package
  10.  
  11. SSYYNNTTAAXX
  12.        #include "fields.h"
  13.  
  14.        typedef struct {
  15.            int nfields;
  16.            int hadnl;
  17.            char *linebuf;
  18.            char **fields;
  19.        } field_t;
  20.  
  21.        #define FLD_RUNS        0x0001
  22.        #define FLD_SNGLQUOTES  0x0002
  23.        #define FLD_BACKQUOTES  0x0004
  24.        #define FLD_DBLQUOTES   0x0008
  25.        #define FLD_SHQUOTES    0x0010
  26.        #define FLD_STRIPQUOTES 0x0020
  27.        #define FLD_BACKSLASH   0x0040
  28.  
  29.        extern field_t *fieldread (FILE * file, char * delims,
  30.                                   int flags, int maxf);
  31.        extern field_t *fieldmake (char * line, int allocated,
  32.                                   char * delims, int flags, int maxf);
  33.        extern int fieldwrite (FILE * file, field_t * fieldp,
  34.                               int delim);
  35.        extern void fieldfree (field_t * fieldp);
  36.  
  37.        extern unsigned int field_line_inc;
  38.        extern unsigned int field_field_inc;
  39.  
  40. DDEESSCCRRIIPPTTIIOONN
  41.        The fields access package eases the common task of parsing
  42.        and  accessing  information which is separated into fields
  43.        by whitespace or other delimiters.  Various options can be
  44.        specified   to   handle   many   common  cases,  including
  45.        selectable delimiters, runs of delimiters, and quoting.
  46.  
  47.        _f_i_e_l_d_r_e_a_d reads one line  from  a  file,  parses  it  into
  48.        fields  as  specified  by  the  parameters,  and returns a
  49.        ffiieelldd__tt structure describing the result.   _f_i_e_l_d_m_a_k_e  per-
  50.        forms  the  same  process  on  a buffer already in memory.
  51.        _f_i_e_l_d_w_r_i_t_e creates an output line from a ffiieelldd__tt structure
  52.        and  writes  it  to  an  output  file.   _f_i_e_l_d_f_r_e_e frees a
  53.        ffiieelldd__tt structure and any associated memory  allocated  by
  54.        the package.
  55.  
  56.        The  ffiieelldd__tt  structure  describes  the fields in a parsed
  57.        line.  A well-behaved  should  only  access  the  nnffiieellddss,
  58.        ffiieellddss,  and  hhaaddnnll  elements; all other elements are used
  59.        internally by the package and are not guaranteed to remain
  60.        the  same  even  though they are documented here.  NNffiieellddss
  61.  
  62.  
  63.  
  64.                               local                             1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. FIELDS(3)                                               FIELDS(3)
  71.  
  72.  
  73.        gives the number of fields in the parsed line,  just  like
  74.        the  aarrggcc  argument to a C program; ffiieellddss is a pointer to
  75.        an array of string pointers, just like the  aarrggvv  argument
  76.        to  a  C program.  As in C, the last field pointer is fol-
  77.        lowed by a null pointer, although the field count  is  the
  78.        preferred  method of accessing fields.  The user may alter
  79.        nnffiieellddss by decreasing it, and may replace any  pointer  in
  80.        ffiieellddss  without harm.  This is often useful in replacing a
  81.        single field with a calculated value preparatory  to  out-
  82.        put.   The  hhaaddnnll  element is nonzero if the original line
  83.        was terminated with a newline when it was parsed; this  is
  84.        used  to accurately reproduce the input when _f_i_e_l_d_w_r_i_t_e is
  85.        called.
  86.  
  87.        The lliinneebbuuff element contains  a  pointer  to  an  internal
  88.        buffer  allocated  by  _f_i_e_l_d_r_e_a_d or provided to _f_i_e_l_d_m_a_k_e.
  89.        This buffer is _n_o_t guaranteed to contain  anything  sensi-
  90.        ble,  although  in  the  current implementation all of the
  91.        field contents can be found therein.
  92.  
  93.        _f_i_e_l_d_r_e_a_d reads a single line  of  arbitrary  length  from
  94.        ffiillee,  allocating  as much memory as necessary to hold it,
  95.        and then parses the line according to its remaining  argu-
  96.        ments.   A  pointer  to  the  parsed  ffiieelldd__tt structure is
  97.        returned, with NNUULLLL returned if an error occurs or if  EEOOFF
  98.        is  reached  on  the input file.  Fields in the input line
  99.        are considered to be separated by any of the delimiters in
  100.        the ddeelliimmss parameter.  For example, if delimiters of ":.;"
  101.        are specified, a line containing "a:b;c.d" would  be  con-
  102.        sidered to have four fields.
  103.  
  104.        The  default parsing of fields considers each delimiter to
  105.        indicate a separate field, and does not allow any quoting.
  106.        This  is  similar  to  the  parsing  done by _c_u_t(1).  This
  107.        behavior can be modified by  specifying  flags.   Multiple
  108.        flags may be OR'ed together.  The available flags are:
  109.  
  110.        FFLLDD__RRUUNNSS
  111.               Consider  runs  of  delimiters  to be the same as a
  112.               single  delimiter,  suppressing  all  null  fields.
  113.               This  is  similar  to the way utilities like _a_w_k(1)
  114.               and _s_o_r_t(1) treat whitespace, but it is not limited
  115.               to whitespace.  A run does not have to consist of a
  116.               single type of delimiter;  if  both  semicolon  and
  117.               colon are delimiters, ";::;" is a run.
  118.  
  119.        FFLLDD__SSNNGGLLQQUUOOTTEESS
  120.               Allow  field  contents  to  be  quoted  with single
  121.               quotes.   Delimiters  and  other  quotes  appearing
  122.               within  single quotes are ignored.  This may appear
  123.               in combination with other quote options.
  124.  
  125.        FFLLDD__BBAACCKKQQUUOOTTEESS
  126.               Allow field contents  to  be  quoted  with  reverse
  127.  
  128.  
  129.  
  130.                               local                             2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. FIELDS(3)                                               FIELDS(3)
  137.  
  138.  
  139.               single quotes.  Delimiters and other quotes appear-
  140.               ing within reverse single quotes are ignored.  This
  141.               may appear in combination with other quote options.
  142.  
  143.        FFLLDD__DDBBLLQQUUOOTTEESS
  144.               Allow field  contents  to  be  quoted  with  single
  145.               quotes.   Delimiters  and  other  quotes  appearing
  146.               within double quotes are ignored.  This may  appear
  147.               in combination with other quote options.
  148.  
  149.        FFLLDD__SSHHQQUUOOTTEESS
  150.               Allow  shell-style quoting.  In the absence of this
  151.               option, quotes are only recognized at the beginning
  152.               of  a  field,  and  characters  following the close
  153.               quote are removed from the field (and are thus lost
  154.               from the input line).  If this option is specified,
  155.               quotes may appear within a field, in the  same  way
  156.               as  they  are  handled  by _s_h(1).  Multiple quoting
  157.               styles may be used in the same field.  If  none  of
  158.               FFLLDD__SSNNGGLLQQUUOOTTEESS, FFLLDD__BBAACCKKQQUUOOTTEESS, or FFLLDD__DDBBLLQQUUOOTTEESS is
  159.               specified with FFLLDD__SSHHQQUUOOTTEESS, all three options  are
  160.               implied.
  161.  
  162.        FFLLDD__SSTTRRIIPPQQUUOOTTEESS
  163.               Remove  quotes  and  backslash  sequences  from the
  164.               field while parsing, converting backslash sequences
  165.               to  their proper ASCII equivalent.  The C sequences
  166.               \a, \b, \f, \n, \r, \v, \x_n_n,  and  \_n_n_n  are  sup-
  167.               ported.   Any other sequence is simply converted to
  168.               the backslashed character, as in _s_h(1).
  169.  
  170.        FFLLDD__BBAACCKKSSLLAASSHH
  171.               Accept standard C-style backslash  sequences.   The
  172.               sequence  will  be converted to an ASCII equivalent
  173.               if FFLLDD__SSTTRRIIPPQQUUOOTTEESS is specified (q.v.).
  174.  
  175.        FFLLDD__NNOOSSHHRRIINNKK
  176.               Don't  shrink  allocated  memory  using  _r_e_a_l_l_o_c(3)
  177.               before  returning.  This option can have a signifi-
  178.               cant effect on performance, especially when  _f_i_e_l_d_-
  179.               _f_r_e_e  is going to be called soon after _f_i_e_l_d_r_e_a_d or
  180.               _f_i_e_l_d_m_a_k_e.  The disadvantage is that slightly  more
  181.               memory  will  be occupied until the field structure
  182.               is freed.
  183.  
  184.        The _m_a_x_f parameter, if nonzero, specifies the maximum num-
  185.        ber  of  fields to be generated.  This may enhance perfor-
  186.        mance if only the first few fields of a long line  are  of
  187.        interest  to  the  caller.   The  actual  number of fields
  188.        returned is one greater than _m_a_x_f, because  the  remainder
  189.        of  the  line will be returned as a single contiguous (and
  190.        uninterpreted, FFLLDD__SSTTRRIIPPQQUUOOTTEESS or FFLLDD__BBAACCKKSSLLAASSHH is  speci-
  191.        fied) field.
  192.  
  193.  
  194.  
  195.  
  196.                               local                             3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. FIELDS(3)                                               FIELDS(3)
  203.  
  204.  
  205.        _f_i_e_l_d_m_a_k_e operates exactly like _f_i_e_l_d_r_e_a_d, except that the
  206.        line parsed is provided by the caller  rather  than  being
  207.        read  from a file.  If the _a_l_l_o_c_a_t_e_d parameter is nonzero,
  208.        the memory pointed to by the _l_i_n_e parameter will automati-
  209.        cally  be  freed  when _f_i_e_l_d_f_r_e_e is called; otherwise this
  210.        memory is the caller's responsibility.  The memory pointed
  211.        to  by  _l_i_n_e is destroyed by _f_i_e_l_d_m_a_k_e.  All other parame-
  212.        ters are the same as for _f_i_e_l_d_r_e_a_d_.
  213.  
  214.        _f_i_e_l_d_w_r_i_t_e writes a set of fields to the  specified  _f_i_l_e,
  215.        separating  them  with the delimiter character _d_e_l_i_m (note
  216.        that this is a character, not a string), and  appending  a
  217.        newline  if  specified  by the _h_a_d_n_l element of the struc-
  218.        ture.  The field structure is not freed.  _f_i_e_l_d_w_r_i_t_e  will
  219.        return nonzero if an I/O error is detected.
  220.  
  221.        _f_i_e_l_d_f_r_e_e  frees the ffiieelldd__tt structure passed to it, along
  222.        with any associated  auxiliary  memory  allocated  by  the
  223.        package  (or  passed to _f_i_e_l_d_m_a_k_e).  The structure may not
  224.        be accessed after _f_i_e_l_d_f_r_e_e is called.
  225.  
  226.        ffiieelldd__lliinnee__iinncc (default 512) and ffiieelldd__ffiieelldd__iinncc  (default
  227.        20) describe the increments to use when expanding lines as
  228.        they are read in and parsed.   _f_i_e_l_d_r_e_a_d  initially  allo-
  229.        cates  a  buffer of ffiieelldd__lliinnee__iinncc bytes and, if the input
  230.        line is larger than that, expands the buffer in increments
  231.        of  the  same  amount  until it is large enough.  If input
  232.        lines are known to consistently reach a certain size, per-
  233.        formance  will  be improved by setting ffiieelldd__lliinnee__iinncc to a
  234.        value larger than that size (larger because there must  be
  235.        room  for  a  null byte).  ffiieelldd__ffiieelldd__iinncc serves the same
  236.        purpose in both _f_i_e_l_d_r_e_a_d and _f_i_e_l_d_m_a_k_e, except that it is
  237.        related to the number of fields in the line rather than to
  238.        the line length.  If the number of fields is  known,  per-
  239.        formance will be improved by setting ffiieelldd__ffiieelldd__iinncc to at
  240.        least one more than that number.
  241.  
  242. RREETTUURRNN VVAALLUUEESS
  243.        _f_i_e_l_d_r_e_a_d and _f_i_e_l_d_m_a_k_e return NNUULLLL if an error occurs  or
  244.        if  EEOOFF  is reached on the input file.  _f_i_e_l_d_w_r_i_t_e returns
  245.        nonzero if an output error occurs.
  246.  
  247. BBUUGGSS
  248.        Thanks to the vagaries of ANSI C, the ffiieellddss..hh header file
  249.        defines  an  auxiliary macro named PP.  If the user needs a
  250.        similarly-named macro, this macro must be undefined first,
  251.        and  the  user's  macro  must be defined after ffiieellddss..hh is
  252.        included.
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.                               local                             4
  263.  
  264.  
  265.